Reference Documentation

Matterport SDK

Usage of the SDK constitutes your agreement with the Matterport SDK Agreement. Email developers@matterport.com with any questions.

Index

Namespaces

Interfaces

Types

Functions

Types

Color

Color: object

An RGB represenation of a color. Each property is normalized to the range [0, 1]

Type declaration

b: number
g: number
r: number

ConditionCallback

ConditionCallback: function

A callback that describes a condition of an IObservable to wait for. Returning true will resolve the promise returned by IObservable.waitUntil

The functional style version of the ICondition

Type declaration

- (data: DataT): boolean
- Parameters
  - data: DataT
  Returns boolean

ConnectOptions

ConnectOptions: object

Options to provide when connecting the sdk

Type declaration

auth: string

A token to provide access to a model

MpSdk

MpSdk: object

The entire MP Sdk returned from a successful call to MP_SDK.connect. The Scene namespace is only available when connecting using the Bundle SDK

// for the Embed SDK
const sdk: MpSdk = await showcaseEmbeddingWindow.MP_SDK.connect(...);
// for the Bundle SDK
const sdk: MpSdk = await bundleWindow.MP_SDK.connect(...);

Type declaration

App: App
Asset: Asset
Camera: Camera
Conversion: Conversion
Floor: Floor
Graph: Graph
Label: Label
Link: Link
Mattertag: Mattertag
Measurements: Measurements
Mode: Mode
Model: Model
OAuth: OAuth
Pointer: Pointer
Renderer: Renderer
Room: Room
Scene: Scene
Sensor: Sensor
Settings: Settings
Sweep: Sweep
Tag: Tag
Tour: Tour
disconnect: typeof disconnect
off: typeof off
on: typeof on

ObserverCallback

ObserverCallback: function

A callback that can be subscribed to changes of an IObservable

The functional style version of the IObserver

Type declaration

- (data: DataT): void
- Parameters
  - data: DataT
  Returns void

Orientation

Orientation: object

An orientation described with Euler-like angles in degrees.

Type declaration

pitch: number
roll: number
yaw: number

Rotation

Rotation: object

Type declaration

x: number
y: number
Optional z?: undefined | number

ShowcaseBundleWindow

ShowcaseBundleWindow: Window & typeof globalThis & object

A Window type that can be used to cast the bundle's iframe's contentWindow to hint at the existance of the MP_SDK object.

const bundleIframe = document.getElementById<HTMLIFrameElement>('showcase');
const showcaseWindow = bundleIframe.contentWindow as ShowcaseBundleWindow;
showcaseWindow.MP_SDK.connect(showcaseWindow);

ShowcaseEmbedWindow

ShowcaseEmbedWindow: Window & typeof globalThis & object

When including the sdk script (<script src='https://static.matterport.com/showcase-sdk/2.0.1-0-g64e7e88/sdk.js'>) on your page, an MP_SDK will be attached to the window object.

This type can be used to cast the window object to access the types available on the MP_SDK object.

const showcaseEmbeddingWindow = window as ShowcaseEmbedWindow;
showcaseEmbeddingWindow.MP_SDK.connect( ... )

Size

Size: object

Type declaration

h: number
w: number

Vector2

Vector2: object

Type declaration

x: number
y: number

Vector3

Vector3: object

Type declaration

x: number
y: number
z: number

Functions

disconnect

disconnect(): void

Stop sending and receiving messages and cleanup any resources associated with the sdk

mpSdk.disconnect();
// mpSdk can no longer make function calls, receive any callbacks to event, observable, or collection

// all sdk functionality should throw errors
try {
  await mpSdk.Mode.moveTo( ... );
} catch (e) {
  console.error(e);
}

Returns void

off

off(event: any, callback: function): Emitter

Unsubscribes from an event.

const callback = (model) => {
  console.log('My model loaded!');
};

// Start listening to the event.
mpSdk.on(mpSdk.Event.MODEL_LOADED, callback);

// Stop listening to the event.
mpSdk.off(mpSdk.Event.MODEL_LOADED, callback);

Parameters

event: any

The event to stop.
callback: function

The original callback.
- - (...any: any[]): void
  - Parameters
    - Rest ...any: any[]
    Returns void

Returns Emitter

on

on(event: App.Event.PHASE_CHANGE, callback: function): Emitter
on(event: Camera.Event.MOVE, callback: function): Emitter
on(event: Floor.Event.CHANGE_START, callback: function): Emitter
on(event: Floor.Event.CHANGE_END, callback: function): Emitter
on(event: Label.Event.POSITION_UPDATED, callback: function): Emitter
on(event: Mattertag.Event.HOVER, callback: function): Emitter
on(event: Mattertag.Event.CLICK, callback: function): Emitter
on(event: Mattertag.Event.LINK_OPEN, callback: function): Emitter
on(event: Mode.Event.CHANGE_START, callback: function): Emitter
on(event: Mode.Event.CHANGE_END, callback: function): Emitter
on(event: Model.Event.MODEL_LOADED, callback: function): Emitter
on(event: Sweep.Event.ENTER, callback: function): Emitter
on(event: Sweep.Event.EXIT, callback: function): Emitter
on(event: Tour.Event.STARTED, callback: function): Emitter
on(event: Tour.Event.STOPPED, callback: function): Emitter
on(event: Tour.Event.ENDED, callback: function): Emitter
on(event: Tour.Event.STEPPED, callback: function): Emitter

deprecated

Use the App.state observable to get phase change notifications.

Parameters
- event: App.Event.PHASE_CHANGE
- callback: function
  - - (app: App.Phase): void
    - Parameters
      - app: App.Phase
      Returns void
Returns Emitter
deprecated

Use the Camera.pose observable to get camera pose change notifications.

Parameters
- event: Camera.Event.MOVE
- callback: function
  - - (pose: Camera.Pose): void
    - Parameters
      - pose: Camera.Pose
      Returns void
Returns Emitter
This event fires when a floor change is starting.

the callback returns the floor index that we are moving to, and the floor index we are moving from.
```
mpSdk.on(mpSdk.Floor.Event.CHANGE_START,
  function(to, from) {
    console.log('Starting to move to floor ' + to + ' from floor ' + from);
  }
);
```
Parameters
- event: Floor.Event.CHANGE_START
- callback: function
  - - (to: number, from: number): void
    - Parameters
      - to: number
      - from: number
      Returns void
Returns Emitter
This event fires when a floor change is ending.

the callback returns the floor index (0 based, counting from the bottom) and the floorName, as set in workshop, or defaulting to the same as floorIndex
```
mpSdk.on(mpSdk.Floor.Event.CHANGE_END,
  function(floorIndex, floorName) {
    console.log('Arrived at floor ' + floorName);
    console.log('it is the ' + floorIndex+1 + 'th floor from the bottom');
  }
);
```
Parameters
- event: Floor.Event.CHANGE_END
- callback: function
  - - (floorIndex: number, floorName: string): void
    - Parameters
      - floorIndex: number
      - floorName: string
      Returns void
Returns Emitter
deprecated
This event fires when the labels' on screen position has changed.
```
mpSdk.on(Label.Event.POSITION_UPDATED,
  function(labels) {
    // Label data updated.
    console.log('On-screen position of first label: ' + JSON.stringify(labels[0].position));
  }
);
```
Parameters
- event: Label.Event.POSITION_UPDATED
- callback: function
  - - (labelData: Label.Label[]): void
    - Parameters
      - labelData: Label.Label[]
      Returns void
Returns Emitter
This event fires when the input pointer hovers onto or out of a mattertag disc.
```
mpSdk.on(mpSdk.Mattertag.Event.HOVER,
  function (tagSid, hovering) {
    if (hovering) {
      console.log('Begin Hovering on', tagSid);
    } else {
      console.log('End Hovering on', tagSid);
    }
  }
);
```
Parameters
- event: Mattertag.Event.HOVER
- callback: function
  - - (tagSid: string, hovering: boolean): void
    - Parameters
      - tagSid: string
      - hovering: boolean
      Returns void
Returns Emitter
This event fires when the input pointer clicks a Mattertag disc.
```
mpSdk.on(mpSdk.Mattertag.Event.CLICK,
  function (tagSid) {
    console.log(tagSid + ' was selected');
  }
);
```
Parameters
- event: Mattertag.Event.CLICK
- callback: function
  - - (tagSid: string): void
    - Parameters
      - tagSid: string
      Returns void
Returns Emitter
This event fires when a mattertag link is opened.
```
mpSdk.on(mpSdk.Mattertag.Event.LINK_OPEN,
  function (tagSid, url) {
    console.log('The link ' + url + ' opened for sid ' + tagSid);
  }
);
```
Parameters
- event: Mattertag.Event.LINK_OPEN
- callback: function
  - - (tagSid: string, url: string): void
    - Parameters
      - tagSid: string
      - url: string
      Returns void
Returns Emitter
This event fires when the camera is starting to transition to a mode.
```
mpSdk.on(mpSdk.Mode.Event.CHANGE_START,
  function(oldMode, newMode){
    console.log('Mode changing from ' + oldMode);
    console.log('Mode changing to  ' + newMode);
  }
);
```
Parameters
- event: Mode.Event.CHANGE_START
- callback: function
  - - (oldMode: string, newMode: string): void
    - Parameters
      - oldMode: string
      - newMode: string
      Returns void
Returns Emitter
This event fires when the camera has completed a transition to a mode.
```
mpSdk.on(mpSdk.Mode.Event.CHANGE_END,
  function(oldMode, newMode){
    console.log('Mode changed from ' + oldMode);
    console.log('Mode changed to  ' + newMode);
  }
);
```
Parameters
- event: Mode.Event.CHANGE_END
- callback: function
  - - (oldMode: string, newMode: string): void
    - Parameters
      - oldMode: string
      - newMode: string
      Returns void
Returns Emitter
This event fires when the model has been loaded.
```
mpSdk.on(mpSdk.Model.Event.MODEL_LOADED,
  function(model){
    console.log('Model sid:' + model.sid);
  }
);
```
Parameters
- event: Model.Event.MODEL_LOADED
- callback: function
  - - (model: Model.ModelData): void
    - Parameters
      - model: Model.ModelData
      Returns void
Returns Emitter
This event fires when first entering a sweep.
```
mpSdk.on(mpSdk.Sweep.Event.ENTER,
  function(oldSweep, newSweep){
    console.log('Leaving sweep ' + oldSweep);
    console.log('Entering sweep ' + newSweep);
  }
);
```
Parameters
- event: Sweep.Event.ENTER
- callback: function
  - - (oldSweep: string, newSweep: string): void
    - Parameters
      - oldSweep: string
      - newSweep: string
      Returns void
Returns Emitter
This event fires when exiting a sweep.
```
mpSdk.on(mpSdk.Sweep.Event.EXIT,
  function(fromSweep, toSweep){
    console.log('Leaving sweep ' + fromSweep);
    console.log('Transitioning to sweep ' + toSweep);
  }
);
```
Parameters
- event: Sweep.Event.EXIT
- callback: function
  - - (fromSweep: string, toSweep: string | undefined): void
    - Parameters
      - fromSweep: string
        
        The exit sweep.
      - toSweep: string | undefined
        
        The destination sweep. This value is only valid for inside mode. It is undefined for floorplan and dollhouse mode.
      Returns void
Returns Emitter
This event fires when the tour has started.
```
mpSdk.on(mpSdk.Tour.Event.STARTED,
  function() {
    console.log('Tour started!');
  }
);
```
Parameters
- event: Tour.Event.STARTED
- callback: function
  - - (): void
    - Returns void
Returns Emitter
This event fires when the tour has stopped.
```
mpSdk.on(mpSdk.Tour.Event.STOPPED,
  function() {
    console.log('Tour stopped!');
  }
);
```
Parameters
- event: Tour.Event.STOPPED
- callback: function
  - - (): void
    - Returns void
Returns Emitter
This event fires when the tour has ended.
```
mpSdk.on(mpSdk.Tour.Event.ENDED,
  function() {
    console.log('Tour ended!');
  }
);
```
Parameters
- event: Tour.Event.ENDED
- callback: function
  - - (): void
    - Returns void
Returns Emitter
This event fires when the tour has stepped.
```
mpSdk.on(mpSdk.Tour.Event.STEPPED,
  function(activeIndex) {
    console.log('Tour has reached step ' + activeIndex);
  }
);
```
Parameters
- event: Tour.Event.STEPPED
- callback: function
  - - (activeIndex: number): void
    - Parameters
      - activeIndex: number
      Returns void
Returns Emitter

Typescript Declarations File

Index

Namespaces

Interfaces

Types

Functions

Types

Color

Type declaration

b: number

g: number

r: number

ConditionCallback

Type declaration

Parameters

data: DataT

Returns boolean

ConnectOptions

Type declaration

auth: string

MpSdk

Type declaration

App: App

Asset: Asset

Camera: Camera

Conversion: Conversion

Floor: Floor

Graph: Graph

Label: Label

Link: Link

Mattertag: Mattertag

Measurements: Measurements

Mode: Mode

Model: Model

OAuth: OAuth

Pointer: Pointer

Renderer: Renderer

Room: Room

Scene: Scene

Sensor: Sensor

Settings: Settings

Sweep: Sweep

Tag: Tag

Tour: Tour

disconnect: typeof disconnect

off: typeof off

on: typeof on

ObserverCallback

Type declaration

Parameters

data: DataT

Returns void

Orientation

Type declaration

pitch: number

roll: number

yaw: number

Rotation

Type declaration

x: number

y: number

Optional z?: undefined | number

ShowcaseBundleWindow

ShowcaseEmbedWindow

Size

Type declaration

h: number

w: number

Vector2

Type declaration

x: number

y: number

Vector3

Type declaration

x: number

y: number

z: number

Functions

disconnect